23 实践课-架构设计落地与 AI 生成内容审计

架构设计落地与 AI 生成内容审计

关联：索引

术语小抄（初学者版）

1）架构设计文档的“最小交付集”（少而够用）

一份可交付的架构设计文档至少包含 5 个部分（缺一就容易返工）：

  1. 范围与边界：系统做什么/不做什么；外部系统有哪些；假设前提是什么。
  2. 模块说明：每个模块“做什么/不做什么”；输入输出是什么；关键责任人（Owner）。
  3. 接口协议：至少写清输入字段、输出字段、错误语义、超时/重试、幂等与追踪字段。
  4. 数据流描述：关键数据从哪里来、如何处理、落到哪里、谁来用、如何回放复现。
  5. 评估与风险：可行性评估（依赖/资源/验证）+ 可扩展性评估（替换/新增/扩容）+ 风险与兜底（安全/失败/人工接管）。

2）架构审计三维（对 AI 生成文档尤其有效）

审计只看三维，避免“看起来很专业但没法落地”：

AI 工具使用：文档模板生成 / 架构审计清单 / 标注数据接入方案（学生可直接复制）

使用方法：把你们的“场景描述、现有模块/接口、数据源与执行系统、约束与风险点”粘贴到 {你的内容}。要求 AI 先产出结构化清单，再产出文档与表格。你必须进行人工审计与回归校验，不可直接照搬。

模板目录：

模板 1：生成《架构设计文档》模板（含示例）

你是工业级智能体架构师。请输出一个《智能体架构设计文档》模板，要求：
1）章节必须包含：范围与边界、模块说明、接口协议、数据流、可行性评估、可扩展性评估、风险与兜底、验证与回归入口；
2）每个章节给“必填项清单”与“合格标准”；
3）用分拣场景给出 1 个简短示例（每节 2~4 行即可），但不要写成长篇散文；
4）输出为 Markdown，可直接复制进文档。

我的材料：{你的内容}

解释与自检：

模板 2：架构审计清单 + 评分表（维度化）

你是技术评审。请输出一个“架构设计文档审计清单 + 评分表”，要求：
1）三大维度：合理性/可落地性/可扩展性；每维至少 8 个检查项；
2）每个检查项必须包含：检查点、常见问题、如何验证（给出可执行的验证方式）；
3）输出一个评分表（0~2 分：不通过/勉强/通过），并给总分解释口径；
4）输出必须严格为 Markdown（表格 + 清单）。

材料：{你的内容}

解释与自检：

模板 3：审计并修补 AI 生成架构文档（输出可替换文本）

你是课堂项目的架构审计员。下面是一份 AI 生成的《架构设计文档》（可能存在幻觉/缺字段/不一致）。请输出：
1）<<<ISSUES>>>：按严重度排序的问题清单（每条说明影响：会导致什么故障/越权/不可测试/不可维护）
2）<<<PATCHES>>>：最小修补文本（给出可以直接替换进文档的段落/表格行）
3）<<<VERIFY>>>：回归验证清单（至少 10 条，覆盖缺信息、冲突、接口不兼容、设备回执丢失、权限不足、超时/限流、数据追溯缺失）

输出要求：
- 三段格式必须严格包含 ISSUES/PATCHES/VERIFY 标记；
- 不要输出长段散文；
- 不能引入课堂未使用的第三方系统（例如“随便上 Kubernetes/Service Mesh”），除非给出最小落地替代方案。

材料：{你的内容}

解释与自检：

模板 4：标注数据接入架构参考方案（数据流 + 接口 + 验证）

你是数据工程 + 智能体落地工程师。请为“分拣场景智能体”生成一份“标注数据接入架构方案”，要求：
1）写清楚数据对象：raw_text、intent、slots、rule_hit、action_plan、device_receipt；
2）写清楚数据流：采集→脱敏→落库→标注→版本管理→训练/评估→回流上线；
3）给出最小接口协议：写 2 个接口（upload_sample / fetch_dataset），包含字段、错误码、trace_id；
4）给出落地验证方法：如何证明数据流真的接入了架构（至少 6 条验证点）；
5）输出为 Markdown（含 1 张 Mermaid 图 + 2 个接口表格）。

材料：{你的内容}

解释与自检：

使用方式：把下面模板复制到你们项目的 ARCHITECTURE.md（或作业文档）中，按“必填项”逐条补齐。写不出来的地方，就是你的架构缺口。

0）文档信息

1）范围与边界（Scope & Boundary）

必填项：

合格标准：

2）模块说明（Modules）

必填项：

模板表格：

模块 子模块 做什么（职责） 不做什么（边界） 关键输入 关键输出 Owner
感知





决策





执行





横切 权限/审计/可观测




合格标准：

3）接口协议（Interface Contracts）

必填项（接口六问口径复用）：

模板表格（至少 3 个接口）：

接口名 调用方→被调用方 输入（字段:类型/约束） 输出（字段:类型） 错误码（可重试？） 超时/幂等 审计字段






trace_id

合格标准：

4）数据流描述（Data Flow）

必填项：

模板表格（至少 6 行）：

数据对象 来源（模块/接口） 处理（校验/脱敏/归一化） 落地位置（表/文件/事件流） 使用者（模块） 回放/复现方式 追溯字段（必填）
raw_text




trace_id / sample_id / ts_ms

合格标准：

5）可行性评估（Feasibility）

必填项（推荐用表格写，不写散文）：

评估项 结论（通过/风险/不通过） 证据 风险与对策
依赖明确
列出 API/ROS2/数据库/标注系统依赖清单 缺依赖就先 mock
接口可验证
至少 1 条回归入口 + 2 个故障注入用例 无法验证则补测试
失败兜底可执行
错误码 + 回执 + 人工接管路径 无兜底就降级
数据可追溯
trace_id 贯穿 + 存储位置 缺字段就补契约
成本/性能可接受
关键路径耗时假设 + 超时策略 不确定就先测量

合格标准：

6）可扩展性评估（Extensibility）

必填项：

推荐写法（至少填 4 条）：

扩展点 预计变化 受影响模块 兼容策略 预计改动范围（小/中/大）
替换机械臂厂商 ROS2 topic/service 变化 执行层适配器 适配层 + 契约不变

合格标准：

7）风险与兜底（Risk & Fallback）

必填项（至少 6 条风险）：

模板表格：

风险 触发条件 影响 监测信号（证据字段/日志） 兜底策略 验证方法
设备误控 意图误判 + 未二次确认 停线/安全事故 trace_id + action_plan 门禁/二次确认/拒绝 故障注入用例

8）验证与回归入口（Verification）

必填项：

示例命令（可按你们项目替换）：

python -m student_agent.tests_smoke

解释与自检：

  1. 如果今天把你们组的架构交给另一个组实现，对方能不能只看文档就开始写代码？卡在哪里？
  2. 如果明天更换机械臂厂商（接口变了），你们预计要改哪些模块？为什么不是全链路都要改？

最常见的 3 类“空洞文档”（看到就要警惕）：

  1. 只写抽象词：高可用、低耦合、可扩展，但没有字段、没有错误码、没有回归入口。
  2. 只画框：模块很多但边界不清，谁调用谁、数据怎么走、失败在哪处理都没说。
  3. 只写流程：把业务过程当架构，缺少接口契约与数据落地位置。

把“能不能做成”拆成 4 个可验证问题：

  1. 依赖明确吗？（外部系统、权限、网络、设备、数据）
  2. 接口可实现可测试吗？（字段/错误码/超时/回归入口）
  3. 失败兜底可执行吗？（拒绝、降级、人工接管、回执）
  4. 证据链可追溯吗？（trace_id、存储位置、回放入口）

把“未来改动是否可控”拆成 3 个检查点：

  1. 复制“架构设计文档模板区”，至少补齐：模块说明表、接口协议表（≥3）、数据流表（≥6）。
  2. 用可行性评估表给出结论：至少标出 3 条“风险”并写对策（补证据动作）。
  3. 用可扩展性评估表补齐 2 个扩展点：换厂商、加场景（或你自选题的真实扩展点）。
  1. AI 生成的架构文档里，哪些内容最容易“看起来对但实际上错”？（提示：接口字段、依赖、兼容策略）
  2. 如果你要把 AI 生成的架构交付上线，你最担心什么风险？你准备怎么验证？

1）幻觉型（最危险）：写了不存在的系统/接口/组件；或者把“建议”写成“已存在”。

2）不一致型：同一个概念在不同段落用不同名字；同一个接口在不同表格里字段不一致；数据流前后矛盾。

3）不可验证型：把关键内容写成抽象描述，没有验证入口与证据字段。

  1. 结构审计：章节是否齐全（最小交付集是否满足）。
  2. 契约审计：接口字段/错误码/追踪字段是否可写可测。
  3. 数据流审计：数据是否能追溯、落地位置是否明确、回放是否可执行。
  4. 回归审计：有没有回归入口、故障注入用例是否覆盖关键风险。

产出要求：

编号 维度 严重度（高/中/低） 问题描述 影响 最小修补建议 如何验证
A-01 可落地性 高 缺少接口字段与错误码 无法实现/无法测试 补齐接口表字段 用故障注入用例验证

要求：不是“把数据收集起来”，而是“把数据流接入架构闭环并能验证”。

flowchart LR
  U[用户/操作员输入] --> P1[感知: 指令采集与脱敏]
  P1 --> P2[感知: 归一化与校验]
  P2 --> D1[决策: 意图识别/规则匹配]
  D1 --> E1[执行: 动作下发/门禁]
  E1 --> E2[执行: 设备回执]
  D1 --> L1[样本落地: 采样与记录]
  E2 --> L1
  L1 --> L2[标注: intent/slots/失败原因]
  L2 --> L3[数据集版本: vX.Y]
  L3 --> T1[训练/评估]
  T1 --> D1

解释与自检：

  1. 能生成 sample_id，并与一次任务的 trace_id 关联。
  2. 能从 trace_id 找到 raw_text、intent/slots、action_plan、device_receipt 的同一条记录。
  3. 能区分“解析失败/权限拒绝/设备超时/设备失败回执”等失败原因，并进入标注字段。
  4. 数据脱敏策略明确（订单号/姓名/手机号等敏感字段不外发）。
  5. 数据集有版本号与说明（采样范围、标注规则版本、变更记录）。
  6. 能用某个数据集版本回放评估：给同样输入，是否能复现同样的路由/动作计划（至少在离线评估层面）。

六、命令与代码：用标准库做“接口协议样例”自检（可选加分，但强烈推荐）

目的：用最小代码把“接口协议写得对不对”变成可运行的验证。

示例：定义一个“动作下发”请求/响应的最小结构，并写一个校验函数（只用 Python 标准库）。

1）保存下面脚本为 contract_check_demo.py：

from __future__ import annotations

import json
from dataclasses import dataclass
from typing import Any, Dict, List, Literal, Tuple

ErrorCode = Literal[
    "OK",
    "AUTH_004",
    "BIZ_004",
    "ROS_002",
    "TIMEOUT_001",
]

@dataclass(frozen=True)
class CommandRequest:
    trace_id: str
    target: Literal["arm", "conveyor", "system"]
    action: str
    params: Dict[str, Any]

@dataclass(frozen=True)
class CommandResponse:
    ok: bool
    trace_id: str
    error_code: ErrorCode
    message: str
    receipt: Dict[str, Any]

def validate_request(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
    issues: List[str] = []
    for key in ("trace_id", "target", "action", "params"):
        if key not in data:
            issues.append(f"missing field: {key}")
    if "trace_id" in data and not isinstance(data["trace_id"], str):
        issues.append("trace_id must be str")
    if "params" in data and not isinstance(data["params"], dict):
        issues.append("params must be object/dict")
    return (len(issues) == 0, issues)

def validate_response(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
    issues: List[str] = []
    for key in ("ok", "trace_id", "error_code", "message", "receipt"):
        if key not in data:
            issues.append(f"missing field: {key}")
    if "ok" in data and not isinstance(data["ok"], bool):
        issues.append("ok must be bool")
    if "trace_id" in data and not isinstance(data["trace_id"], str):
        issues.append("trace_id must be str")
    if "error_code" in data and data["error_code"] not in (
        "OK",
        "AUTH_004",
        "BIZ_004",
        "ROS_002",
        "TIMEOUT_001",
    ):
        issues.append("error_code is not in allowed set")
    return (len(issues) == 0, issues)

def main() -> None:
    req = {
        "trace_id": "t-001",
        "target": "arm",
        "action": "pick_and_place",
        "params": {"from": "bin_A", "to": "bin_B", "speed": 0.5},
    }
    resp_ok = {
        "ok": True,
        "trace_id": "t-001",
        "error_code": "OK",
        "message": "accepted",
        "receipt": {"device_task_id": "d-778", "status": "accepted"},
    }

    ok1, issues1 = validate_request(req)
    ok2, issues2 = validate_response(resp_ok)
    print(json.dumps({"request_ok": ok1, "request_issues": issues1}, ensure_ascii=False))
    print(json.dumps({"response_ok": ok2, "response_issues": issues2}, ensure_ascii=False))

if __name__ == "__main__":
    main()

逐段解释与自检要点：

2）运行脚本（PowerShell）：

python .\contract_check_demo.py

解释与自检：

课程思政（融入点：地方苹果智能分拣系统）

  1. 如果你是本地果业合作社的技术支持，你最希望系统在“扩展/变更”时具备什么能力？对应到文档里该写在哪一节？
  2. 如果发生一次错分拣，如何用数据流与 trace_id 复盘原因，并把结论回流到标注数据与规则/模型更新中？

作业：布置

1）提交完整的智能体架构设计文档（含模块说明、接口协议、数据流、可行性评估）。

2）提交 AI 生成架构的审计报告（150 字左右，含问题清单、优化方案）。

3）提交标注数据数据流落地的技术方案草稿（100 字左右）。

Markdown 自检清单（提交前自己勾一遍）